<div class="tmd-doc">
<h1 class="tmd-header-1">
Golds
</h1>
<p></p>
<div class="tmd-usual">
<span class="tmd-bold"><span class="tmd-italic">Golds</span></span> is an experimental Go local docs server, a Go docs generator, and a Go code reader.
</div>
<p></p>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
Demo: <a href="https://docs.go101.org/index.html">docs and source code of standard packages</a> (generated with <code class="tmd-code-span">GOEXPERIMENT=arenas,jsonv2 golds -gen -nouses -only-list-exporteds -render-doclinks -theme=dark std</code>).
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
Code is <a href="https://github.com/go101/golds">hosted on Github</a>. Any feedback, including PR and bug reports, are welcome.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
Please follow <a href="https://twitter.com/zigo_101">@zigo_101</a> to get the latest news of <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> (and all kinds of Go details/facts/tips/etc.).
</div>
</li>
</ul>
<p></p>
<p></p>
<h2 class="tmd-header-2">
Features and Limitations
</h2>
<p></p>
<div class="tmd-usual">
Please read <a href="https://github.com/go101/golds">the project home page</a> for details.
</div>
<p></p>
<p></p>
<h2 class="tmd-header-2">
Installation
</h2>
<p></p>
<div class="tmd-usual">
Run <code class="tmd-code-span">go install go101.org/golds@latest</code> to install Golds. If the tool program name <code class="tmd-code-span">golds</code> conflicts with another tool with the same name you are using, you can run any of the following commands to install <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> as a program with a different name:
</div>
<p></p>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
Go docs generator: run <code class="tmd-code-span">go install go101.org/golds/godoge@latest</code>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
Go code reader: run <code class="tmd-code-span">go install go101.org/golds/gocore@latest</code>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
Go local docs (mainly for legacy. <code class="tmd-code-span">gold</code> was the old default program name of <span class="tmd-bold"><span class="tmd-italic">Golds</span></span>): run <code class="tmd-code-span">go install go101.org/golds/gold@latest</code>
</div>
</li>
</ul>
<p></p>
<div class="tmd-usual">
You may also clone this project firstly, then run the <code class="tmd-code-span">go install</code> command in the respective program folders to install <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> as <code class="tmd-code-span">golds</code>, <code class="tmd-code-span">godoge</code>, or <code class="tmd-code-span">gocore</code>.
</div>
<p></p>
<div class="tmd-usual">
(NOTE: Go commands will install produced binaries into the Go binary installation path specified by the <code class="tmd-code-span">GOBIN</code> environment variable, which defaults to the path of the <code class="tmd-code-span">bin</code> subfolder under the first path specified in the <code class="tmd-code-span">GOPATH</code> environment variable, which defaults to the path of the <code class="tmd-code-span">go</code> subfolder under the path specified by the <code class="tmd-code-span">HOME</code> environment variable. Please specify the Go binary installation path in the <code class="tmd-code-span">PATH</code> environment variable to run <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> commands successfully.)
</div>
<p></p>
<h2 class="tmd-header-2">
Usages
</h2>
<p></p>
<div class="tmd-usual">
The main usage of <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> is to start a local docs server for a project, to either read package docs or study source code of the project. We can
</div>
<p></p>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
run <code class="tmd-code-span">golds .</code> to show docs of the package in the current directory (and all its dependency packages).
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
run <code class="tmd-code-span">golds ./...</code> to show docs of all the package under the current directory (and all their dependency packages).
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
run <code class="tmd-code-span">golds toolchain</code> (or <code class="tmd-code-span">golds cmd</code>) to show docs of official toolchain packages.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
run <code class="tmd-code-span">golds std</code> to show docs of standard packages. <code class="tmd-code-span">std</code> can be mixed with any one of the above three arguments.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
run <code class="tmd-code-span">golds aPackage[/...][@aVersion]</code> to show docs of the specified packages (and all their dependency packages).
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
run <code class="tmd-code-span">golds foo.go bar.go baz.go</code> to show docs of the specified files (and all their dependency packages).
</div>
</li>
</ul>
<p></p>
<div class="tmd-usual">
Each of the above commands will open a browser window automatically. We can use the <code class="tmd-code-span">-s</code> or <code class="tmd-code-span">-silent</code> options to turn off the behavior.
</div>
<p></p>
<div class="tmd-usual">
The second usage of <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> is to generate static HTML doc pages for a project, with the <code class="tmd-code-span">-gen</code> option:
</div>
<p></p>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">golds -gen -dir=generated -nouses .</code>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">golds -gen -dir=generated -nouses ./...</code>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">golds -gen -dir=generated -nouses std</code>
</div>
</li>
</ul>
<p></p>
<div class="tmd-usual">
The <code class="tmd-code-span">-dir</code> option is optional and its default value is <code class="tmd-code-span">.</code>(the working directory). The <code class="tmd-code-span">-nouses</code> option used here is to generate docs with moderate sizes.
</div>
<p></p>
<div class="tmd-usual">
The option <code class="tmd-code-span">-source-code-reading</code> is used to control how to generate source code pages. Available values:
</div>
<p></p>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">plain</code>: generate simpler source code pages (no highlighting and no code navigations to reduce the total page size by 1/6 of the full docs size).
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">highlight</code>: only highlight keywords and basic literals (no code navigations).
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">rich</code>: rich code reading experience.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">external</code>: link to external code host websites (try its best, use <code class="tmd-code-span">highlight</code> when failed).
</div>
</li>
</ul>
<p></p>
<div class="tmd-usual">
The option <code class="tmd-code-span">-allow-network-connection</code> specifies whether or not network connections are allowed in determining external code host websites.
</div>
<p></p>
<div class="tmd-usual">
Options to control generated docs sizes:
</div>
<p></p>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">-nouses</code>: don't generate identifier-uses pages (identifier-uses pages will occupy about 9/10 of the total page count and 2/3 of the full docs size).
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">-source-code-reading=plain</code>
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">-only-list-exporteds</code>: don't list unexported package-level code elements in package-details pages.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">-compact</code> is a shortcut of the combination of the above compact docs generation options.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
Using <code class="tmd-code-span">-source-code-reading=external</code> along with <code class="tmd-code-span">-compact</code> will further reduce the generated docs size.
</div>
</li>
</ul>
<p></p>
<div class="tmd-usual">
The size of the docs generated by <code class="tmd-code-span">golds -gen -compact ./...</code> is about 1/6 of <code class="tmd-code-span">golds -gen ./...</code> and about 1/2 of <code class="tmd-code-span">golds -gen -nouses ./...</code>. The size of the docs generated by <code class="tmd-code-span">golds -gen -compact -source-code-reading=external ./...</code> is about 1/6 of <code class="tmd-code-span">golds -gen -compact ./...</code>.
</div>
<p></p>
<div class="tmd-usual">
The <code class="tmd-code-span">-wdpkgs-listing</code> option is used to specify how to list the packages in the working directory. Available values include
</div>
<p></p>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">general</code> (the default, list them with others by alphabetical order)
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">promoted</code> (list them before others)
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
<code class="tmd-code-span">solo</code> (list them without others)
</div>
</li>
</ul>
<p></p>
<div class="tmd-usual">
The <code class="tmd-code-span">-render-doclinks</code> option is used to control whether or not to render links in docs.
</div>
<p></p>
<div class="tmd-usual">
The <code class="tmd-code-span">-theme</code> option is used to control page styling Supported values include <code class="tmd-code-span">auto</code> (default), <code class="tmd-code-span">light</code> and <code class="tmd-code-span">dark</code>. The <code class="tmd-code-span">auto</code> value is equivalent to <code class="tmd-code-span">light</code> plus custom styling set in the <code class="tmd-code-span">UserConfigDir/golds/custom.css</code> file (if it exists).
</div>
<p></p>
<div class="tmd-usual">
The third usage of <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> is to serve files within a directory ("Golds" also means Go local directory server). For example, we can run <code class="tmd-code-span">golds -dir=.</code> (or simply <code class="tmd-code-span">golds</code>) from the HTML docsgeneration directory to view the generated docs in browser. The <code class="tmd-code-span">-s</code> and <code class="tmd-code-span">-silent</code> options also work in this mode.
</div>
<p></p>
<div class="tmd-usual">
The <code class="tmd-code-span">golds</code> command recognizes the <code class="tmd-code-span">GOOS</code> and <code class="tmd-code-span">GOARCH</code> environment variables.
</div>
<p></p>
<h2 class="tmd-header-2">
FAQ
</h2>
<p></p>
<details class="tmd-reveal">
<summary class="tmd-reveal-header tmd-usual">
What does <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> mean?
</summary>
<div class="tmd-reveal-content">
<div class="tmd-base">
<p></p>
<div class="tmd-usual">
"Golds" is an abbreviation of <span class="tmd-bold">Go</span> <span class="tmd-bold">l</span>ocal <span class="tmd-bold">d</span>ocs <span class="tmd-bold">s</span>erver. It also means <span class="tmd-bold">Go</span> <span class="tmd-bold">l</span>ocal <span class="tmd-bold">d</span>irectory <span class="tmd-bold">s</span>erver.
</div>
</div>
</div>
</details>
<p></p>
<details class="tmd-reveal">
<summary class="tmd-reveal-header tmd-usual">
Why <span class="tmd-bold"><span class="tmd-italic">Golds</span></span>?
</summary>
<div class="tmd-reveal-content">
<div class="tmd-base">
<p></p>
<div class="tmd-usual">
I didn't find a Go tool showing type implementation relations, so I decided to write one. During achieving this, I got many new ideas which form the tool to the final <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> design.
</div>
<p></p>
<div class="tmd-usual">
I also have some different design opinions from the official <code class="tmd-code-span">godoc</code> program developers, such as <a href="https://github.com/golang/go/issues/28006">the manner of listing factory functions</a>.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
Golds also tries to fix some other shortcomings of <code class="tmd-code-span">godoc</code> and <code class="tmd-code-span">go doc</code>, such as <a href="https://github.com/golang/go/issues/6600">this</a>, <a href="https://github.com/golang/go/issues/40360">this</a> and <a href="https://github.com/golang/go/issues/5860">this</a>.
</div>
</div>
</div>
</details>
<p></p>
<details class="tmd-reveal">
<summary class="tmd-reveal-header tmd-usual">
Is <span class="tmd-bold"><span class="tmd-italic">Golds</span></span> recommended to run locally?
</summary>
<div class="tmd-reveal-content">
<div class="tmd-base">
<p></p>
<div class="tmd-usual">
Yes. But if you do want to serve your package docs on Internet, it is best to serve the generated HTML static doc pages to lower the server cost.
</div>
</div>
</div>
</details>
<p></p>
<details class="tmd-reveal">
<summary class="tmd-reveal-header tmd-usual">
What are the requirements to run <span class="tmd-bold"><span class="tmd-italic">Golds</span></span>?
</summary>
<div class="tmd-reveal-content">
<div class="tmd-base">
<p></p>
<div class="tmd-usual">
If a Go project needs cgo, then a proper C/C++ compiler is needed.
</div>
<p></p>
<div class="tmd-usual">
Some projects might need large memory capacity to analyze. For example, the recommended memory capacity to analyze the Kubernetes project is 8G+. However, 500M to 2G memory is okay for most Go projects.
</div>
</div>
</div>
</details>
</div>
